Preference Packs/de

Einleitung

Ein Voreinstellungspaket (Preference Pack) stellt eine Sammlung von Benutzervoreinstellungen, zum Verteilen zur Verfügung (eingeführt in 0.20); es kann als Addon installiert und die Einstellungen so als kompletter Satz angewendet werden. Jede Benutzereinstellung, die in der user.cfg festgelegt werden kann, kann auch in einem Voreinstellungspaket verwendet werden. Die Anwendung eines Voreinstellungspakets setzt alle die Variablen, die in der mitgelieferten CFG-Datei vorhanden sind und lässt alle anderen Einstellungen unverändert. Diese Pakete können z.B. verwendet werden, um Themen (Themes) zu erstellen, indem man ein selbsterstelltes Stylesheet zusammen mit einem Satz Benutzereinstellungen bündelt, die unterschiedliche Farben und Ausführungsarten von Elementen in FreeCAD steuern, die nicht von dem Stylesheet festgelegt werden.

Hauptbenutzerschnittstelle für Voreinstellungspakete

Die meisten Benutzerinteraktionen mit installierten Einstellungs-Paketen erfolgen über die Registerkarte Allgemein im Abschnitt Allgemeine Einstellungen des Voreinstellungseditor.

Anwendung eines installierten Pakets

Um ein Präferenzpaket anzuwenden, klickt man auf die Schaltfläche Anwenden neben seinem Namen auf der Registerkarte Allgemein des Voreinstellungseditors. Der Kern eines Voreinstellungspakets ist eine Reihe von Benutzereinstellungen. Bei der Anwendung eines Pakets wird jede dieser Einstellungen auf den im Paket definierten Wert geändert. Optional kann der Autor des Pakets ein Makro für vor und/oder nach der Anwendung hinzugefügt haben, das ebenfalls ausgeführt werden kann. Da Pakete möglicherweise große (und möglicherweise unerwünschte) Änderungen an Ihren Benutzereinstellungen vornehmen können, wird eine mit einem Zeitstempel versehene Sicherungskopie der ursprünglichen Einstellungen erstellt und unter FREECAD_USER_DATA/SavedPreferencePacks/Backups gespeichert. Diese Sicherungskopien werden eine Woche lang aufbewahrt.

Ein neues Paket erstellen

Pakete können manuell erstellt oder mithilfe der Schaltfläche Speichern neu... auf der Registerkarte Allgemein des Voreinstellungseditor schnell erstellt werden. Durch Klicken auf die Schaltfläche wird ein Dialogfeld angezeigt, in dem man einen Namen für das neue Paket eingeben muss, sowie eine Reihe von Kontrollkästchen, mit denen man festlegen kann, dass nur eine Teilmenge der Einstellungen gespeichert werden soll.

Aufgrund der Art und Weise, wie FreeCAD intern Einstellungen verwendet, können nur Elemente, die in diesen Vorlagendateien enthalten sind, mit diesem Verfahren automatisch gespeichert werden. Elemente, die nicht in den Vorlagendateien enthalten sind, müssen manuell in die *.cfg-Datei des Pakets aufgenommen werden. Es gibt keine integrierte Begrenzung dafür, welche Einstellungselemente in ein Einstellungs-Paket aufgenommen werden können, aber Autoren werden dringend davon abgeraten, die vom Benutzer eingestellte Sprache zu ändern, die Liste der zuletzt verwendeten Dateien zu modifizieren oder irgendetwas zu ändern, das mit einem temporären UI-Zustand zusammenhängt (z. B. die gespeicherte Größe eines anpassbaren Fensters usw.).

Details zur Vorlage

In diesen Abschnitten sind alle in den integrierten Vorlagen enthaltenen Einstellungen aufgeführt. Derzeit konzentrieren sie sich auf Elemente, die das Erscheinungsbild betreffen, aber Pull-Anfragen und Vorschläge im Forum für weitere Ergänzungen sind willkommen. Installierte Addons können auch eigene Vorlagen bereitstellen (die hier nicht dokumentiert sind). Ganz rechts neben jedem Eintrag auf "Erweitern" klicken, um die Liste anzuzeigen.

Struktur der Voreinstellungspakete

Der Kern der meisten Präferenzpakete besteht zwar aus einer einzigen Konfigurationsdatei, aufgrund ihres Designs für die Verteilung sind jedoch auch einige zusätzliche Strukturen erforderlich. Ein Paket wird durch vier Kerndateien definiert, die in der folgenden Verzeichnisstruktur angeordnet sind (für ein Präferenzpaket mit dem Namen "SamplePreferencePack"):

• package.xml
• SamplePreferencePack/
  • SamplePreferencePack.cfg
  • pre.FCMacro
  • post.FCMacro

Die Datei Package Metadata (package.xml) definiert den Namen des Voreinstellungspakets und ermöglicht die Zuweisung weiterer Metadatenelemente wie Versionsnummer, Autoreninformationen und Tags (die in der Hauptoberfläche als durch Kommas getrennte Liste angezeigt werden). Für ein Präferenzpaket, das wie oben beschrieben über die GUI gespeichert wurde, wird eine einzelne package.xml-Datei im Verzeichnis FREECAD_USER_DATA/SavedPreferencePacks/ erstellt. Diese Datei wird verwendet, um Details wie den Namen und die Tags aller vom Benutzer gespeicherten Präferenzpakete zu beschreiben. Um den Namen oder die Tags eines Packs zu ändern, muss diese Datei manuell mit einem Texteditor bearbeitet werden. Sie kann auch als Vorlage für verteilte Präferenzpakete dienen: Der Autor eines verteilten Packs kann zunächst ein Pack lokal speichern und dann das Unterverzeichnis des Packs und diese globale package.xml-Datei als Ausgangspunkt kopieren und die kopierte package.xml-Datei so ändern, dass sie nur auf das für die Verteilung gepackte Pack verweist.

Je nach den Anforderungen des Pakets können auch andere Dateien in einer Distribution enthalten sein. Ein gut zusammengestelltes Präferenzpaket für die Verteilung eines visuellen Themas namens "DarkSide" für FreeCAD könnte wie folgt aussehen:

• package.xml
• resources/
  • icons/
    • DarkSide.svg
• DarkSide/
  • DarkSide.cfg
  • DarkSide.qss

Es ist zu beachten, dass die Dateien pre.FCMacro und post.FCMacro weggelassen werden können, die oft nicht erforderlich sind, sowie das Hinzufügen eines Symbols (zur Anzeige durch den Addon-Manager) und die Einbindung einer qss-Datei (auf die dann in der Konfigurationsdatei „DarkSide.cfg” verwiesen wird).

Die Pre- und Post-Makrodateien sind Standard-FreeCAD-Python-Makros und können alle in einem solchen Makro gültigen Befehle enthalten. Wenn das Pre.FCMacro eine Ausnahme (jeglicher Art) auslöst, wird die Anwendung des Voreinstellungspakets abgebrochen. Wenn das Post.FCMacro eine Ausnahme (jeglicher Art) auslöst, wird die Anwendung des Pakets unter Verwendung der vor seiner Anwendung erstellten Sicherung rückgängig gemacht. Diese Makros können beispielsweise verwendet werden, um den Benutzer zur Annahme der Lizenz aufzufordern oder um zu überprüfen, ob er mit dem endgültigen Zustand seines Systems nach der Anwendung zufrieden ist.

Die Datei package.xml für dieses Beispielpaket könnte wie folgt aussehen:

<?xml version="1.0" encoding="UTF-8" standalone="no" ?>
<package format="1" xmlns="https://wiki.freecad.org/Package_Metadata">
  <name>DarkSide Theme Package</name>
  <description>A preference pack including a stylesheet and other GUI color information for a Dark mode.</description>
  <version>1.0.0</version>
  <maintainer email="chennes@pioneerlibrarysystem.org">Chris Hennes</maintainer>
  <license file="LICENSE">GPLv3</license>
  <url type="repository" branch="main">https://github.com/chennes/DarkSideThemePackage</url>
  <icon>resources/icons/DarkSide.svg</icon>

  <content>
    <preferencepack>
      <name>DarkSide</name>
      <description>Dark mode color scheme</description>
      <tag>color</tag>
      <tag>stylesheet</tag>
      <tag>dark</tag>
      <file>DarkSide.qss</file>
    </preferencepack>
  </content>

</package>

Vorlagen in Ihr Addon einbinden

Viele Addons verfügen über benutzerdefinierbare Einstellungsinformationen, die zur Datei user.cfg hinzugefügt werden. Ein Addon-Autor kann auch eine Vorlagendatei für Einstellungs-Packs bereitstellen, in der die Benutzerkonfigurationsvariablen aufgeführt sind, die mit der oben beschriebenen Methode "Neues Pack speichern" automatisch gespeichert werden können. Um diese Vorlagendateien einzubinden, sollten Addon-Autoren in ihrem Paket ein Unterverzeichnis mit dem Namen "PreferencePackTemplates" oder "preference_pack_templates" erstellen. In diesem Ordner sollten sich eine oder mehrere *.cfg-Dateien befinden: Jede davon muss eine gültige, wohlgeformte user.cfg-XML-Datei sein, die eine oder mehrere Konfigurationsvariablen enthält, die auf ihre Standardwerte gesetzt sind. Der Name der Datei sollte ihren Zweck widerspiegeln, z. B. "colors.cfg", "active_tabs.cfg" usw. Diese Dateien werden dem Benutzer beim Speichern eines neuen Präferenzpakets angezeigt, wobei jede Datei einen ankreuzbaren Eintrag in der Liste der zu speichernden Elemente erhält. Der Dateiname wird zur Erstellung des UI-Eintrags verwendet, wobei Unterstriche durch Leerzeichen ersetzt werden (und die Erweiterung weggelassen wird).

Verteilen eines Packs

Voreinstellungspakete werden genauso wie Externe Arbeitsbereiche über den Addon-Manager verteilt. Um ein Paket manuell zu installieren, klont man das Paket-Repository mit git in das FreeCAD-Datenverzeichnis (App.getUserAppDataDir() in die Python-Konsole eingeben, um diesen Pfad zu erhalten) in ein Unterverzeichnis namens "Preference Packs". Es ist zu beachten, dass vom Benutzer installierte Pakete mit dem gleichen Namen wie ein enthaltenes Paket Vorrang haben.

Siehe auch Private Voreinstellungspakete.